View Hierarchy Functions

Each window (BWindow object) in a BeOS application has an associated tree of BView objects; these BView objects may be contained directly in the BWindow, or they may be contained in other BView objects which belong to the window, hence the tree structure. The functions described in this section are used to construct and use these trees of BView instances. You might want to also read up on the BWindow::AddChild() function, which works much the same as the BView::AddChild() function described below, but which adds a view to a window instead of to another view.

A number of view-hierarchy-related functions can be found in Hook Functions.

AddChild() , RemoveChild()

void AddChild(BView *aView, BView *sibling = NULL) bool RemoveChild(BView *aView)

AddChild() makes aView a child of the BView, provided that aView doesn't already have a parent. The new child is added to the BView's list of children immediately before the named sibling BView. If the sibling is NULL (as it is by default), aView isn't added in front of any other view—in other words, it's added to the end of the list. If the BView is attached to a window, aView and all its descendants become attached to the same window. Each of them is notified of this change through AttachedToWindow() and AllAttached() function calls.

AddChild() fails if aView already belongs to a view hierarchy. A view can live with only one parent at a time. It also fails if sibling is not already a child of the BView.

RemoveChild() severs the link between the BView and aView, so that aView is no longer a child of the BView; aView retains all its own children and descendants, but they become an isolated fragment of a view hierarchy, unattached to a window. Each removed view is notified of this change through DetachedFromWindow() and AllDetached() function calls.

A BView must be removed from a window before it can be destroyed.

If it succeeds in removing aView, RemoveChild() returns true. If it fails, it returns false. It will fail if aView is not, in fact, a current child of the BView.

When a BView object becomes attached to a BWindow, two other connections are automatically established for it:

• The view is added to the BWindow's flat list of BHandler objects, making it an eligible target for messages the BWindow dispatches.

• The BView's parent view becomes its next handler. Messages that the BView doesn't recognize will be passed to its parent.

Removing a BView from a window's view hierarchy also removes it from the BWindow's flat list of BHandler objects; the BView will no longer be eligible to handle messages dispatched by the BWindow.

See also: BWindow::AddChild(), BLooper::AddHandler(), BHandler::SetNextHandler(), RemoveSelf(), AttachedToWindow(), DetachedFromWindow()

	ChildAt()  see Parent()
	CountChildren()  see Parent()

FindView()

BView *FindView(const char *name) const

Returns the BView identified by name, or NULL if the view can't be found. Names are assigned by the BView constructor and can be modified by the SetName() function inherited from BHandler.

FindView() begins the search by checking whether the BView's name matches name. If not, it continues to search down the view hierarchy, among the BView's children and more distant descendants. To search the entire view hierarchy, use the BWindow version of this function.

See also: BWindow::FindView(), BHandler::SetName()

MoveBy() , MoveTo()

void MoveBy(float horizontal, float vertical) void MoveTo(BPoint point) void MoveTo(float x, float y)

These functions move the view in its parent's coordinate system without altering its size.

MoveBy() adds horizontal coordinate units to the left and right components of the frame rectangle and vertical units to the top and bottom components. If horizontal and vertical are positive, the view moves downward and to the right. If they're negative, it moves upward and to the left.

MoveTo() moves the upper left corner of the view to point—or to (x, y)—in the parent view's coordinate system and adjusts all coordinates in the frame rectangle accordingly.

Neither function alters the BView's bounds rectangle or coordinate system.

None of the values passed to these functions should specify fractional coordinates; the sides of a view must line up on screen pixels. Fractional values will be rounded to the closest whole number.

If the BView is attached to a window, these functions cause its parent view to be updated, so the BView is immediately displayed in its new location. If it doesn't have a parent or isn't attached to a window, these functions merely alter its frame rectangle.

See also: FrameMoved(), ResizeBy(), Frame()

NextSibling()  see Parent()

Parent() , NextSibling() , PreviousSibling() , ChildAt() , CountChildren()

BView *Parent(void) const BView *NextSibling(void) const BView *PreviousSibling(void) const BView *ChildAt(int32 index) const int32 CountChildren(void) const

These functions provide various ways of navigating the view hierarchy. Parent() returns the BView's parent view, unless the parent is the top view of the window, in which case it returns NULL. It also returns NULL if the BView doesn't belong to a view hierarchy and has no parent.

All the children of the same parent are arranged in a linked list. NextSibling() returns the next sibling of the BView in the list, or NULL if the BView is the last child of its parent. PreviousSibling() returns the previous sibling of the BView, or NULL if the BView is the first child of its parent.

ChildAt() returns the view at index in the list of the BView's children, or NULL if the BView has no such child. Indices begin at 0 and there are no gaps in the list. CountChildren() returns the number of children the BView has. If the BView has no children, CountChildren() returns NULL, as will ChildAt() for all indices, including 0.

To scan the list of a BView's children, you can increment the index passed to ChildAt() until it returns NULL. However, it's more efficient to ask for the first child and then use NextSibling() to walk down the sibling list. For example:

BView *child; if ( child = myView->ChildAt(0) ) {    while ( child ) {       . . .       child = child->NextSibling();    } }

	PreviousSibling()  see Parent() See also: AddChild()
	RemoveChild()  see AddChild()

RemoveSelf()

bool RemoveSelf(void)

Removes the BView from its parent and returns true, or returns false if the BView doesn't have a parent or for some reason can't be removed from the view hierarchy.

This function acts just like RemoveChild(), except that it removes the BView itself rather than one of its children.

See also: AddChild()